From 7fdf2e0bde1786b99082e64184476f28169206fd Mon Sep 17 00:00:00 2001 From: Ryan Lortie Date: Wed, 11 Jan 2012 12:56:35 +0100 Subject: [PATCH] document GtkActionable This should have been done before it was merged... --- docs/reference/gtk/gtk-docs.sgml | 1 + docs/reference/gtk/gtk3-sections.txt | 26 +++++ docs/reference/gtk/gtk3.types | 1 + gtk/gtkactionable.c | 144 +++++++++++++++++++++++++++ 4 files changed, 172 insertions(+) diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index 9be29d7de0..06b94b6167 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -339,6 +339,7 @@ Application support + diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt index 4aa6181036..6f0402506f 100644 --- a/docs/reference/gtk/gtk3-sections.txt +++ b/docs/reference/gtk/gtk3-sections.txt @@ -7057,6 +7057,32 @@ gtk_application_window_get_type GtkApplicationWindowPrivate +
+gtkactionable +GtkActionable +GtkActionable +GtkActionableInterface + + +gtk_actionable_get_action_name +gtk_actionable_set_action_name + + +gtk_actionable_get_action_target_value +gtk_actionable_set_action_target_value +gtk_actionable_set_action_target + + +gtk_actionable_set_detailed_action_name + + +gtk_actionable_get_type +GTK_ACTIONABLE +GTK_ACTIONABLE_GET_IFACE +GTK_IS_ACTIONABLE +GTK_TYPE_ACTIONABLE +
+
gtkgrid GtkGrid diff --git a/docs/reference/gtk/gtk3.types b/docs/reference/gtk/gtk3.types index 4a035af995..7fe92ad4cb 100644 --- a/docs/reference/gtk/gtk3.types +++ b/docs/reference/gtk/gtk3.types @@ -6,6 +6,7 @@ gtk_accel_group_get_type gtk_accel_label_get_type gtk_accel_map_get_type gtk_accessible_get_type +gtk_actionable_get_type gtk_action_get_type gtk_action_group_get_type gtk_activatable_get_type diff --git a/gtk/gtkactionable.c b/gtk/gtkactionable.c index f78474e8f0..f49cd70318 100644 --- a/gtk/gtkactionable.c +++ b/gtk/gtkactionable.c @@ -26,6 +26,43 @@ #include "gtkwidget.h" #include "gtkintl.h" +/** + * SECTION:gtkactionable + * @title: GtkActionable + * @short_description: an interface for widgets that can be associated + * with actions + * + * This interface provides a convenient way of associating widgets with + * actions on a #GtkApplicationWindow or #GtkApplication. + * + * It primarily consists of two properties: "action-name" and + * "action-target". There are also some convenience APIs for setting + * these properties. + * + * This interface is presently only meaningful if used on a widget that + * is (or will be) located inside of a #GtkApplicationWindow and can + * only be used to associate the widget with actions on that window, or + * its associated #GtkApplication. + * + * Since: 3.4 + **/ + +/** + * GtkActionable: + * + * An opaque pointer type. + **/ + +/** + * GtkActionableInterface: + * @get_action_name: virtual pointer for gtk_actionable_get_action_name + * @set_action_name: virtual pointer for gtk_actionable_set_action_name + * @get_action_target_value: virtual pointer for gtk_actionable_get_action_target_value + * @set_action_target_value: virtual pointer for gtk_actionable_set_action_target_value + * + * The interface vtable for #GtkActionable. + **/ + G_DEFINE_INTERFACE (GtkActionable, gtk_actionable, GTK_TYPE_WIDGET) static void @@ -42,6 +79,18 @@ gtk_actionable_default_init (GtkActionableInterface *iface) G_VARIANT_TYPE_ANY, NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); } +/** + * gtk_actionable_get_action_name: + * @actionable: a #GtkActionable widget + * + * Gets the action name for @actionable. + * + * See gtk_actionable_set_action_name() for more information. + * + * Returns: the action name, or %NULL if none is set + * + * Since: 3.4 + **/ const gchar * gtk_actionable_get_action_name (GtkActionable *actionable) { @@ -51,6 +100,25 @@ gtk_actionable_get_action_name (GtkActionable *actionable) ->get_action_name (actionable); } +/** + * gtk_actionable_set_action_name: + * @actionable: a #GtkActionable widget + * @action_name: an action name, or %NULL + * + * Specifies the name of the action with which this widget should be + * associated. If @action_name is %NULL then the widget will be + * unassociated from any previous action. + * + * Usually this function is used when the widget is located (or will be + * located) within the hierarchy of a #GtkApplicationWindow. + * + * Names are of the form "win.save" or "app.quit" for actions on the + * containing #GtkApplicationWindow or its associated #GtkApplication, + * respectively. This is the same form used for actions in the #GMenu + * associated with the window. + * + * Since: 3.4 + **/ void gtk_actionable_set_action_name (GtkActionable *actionable, const gchar *action_name) @@ -61,6 +129,18 @@ gtk_actionable_set_action_name (GtkActionable *actionable, ->set_action_name (actionable, action_name); } +/** + * gtk_actionable_get_action_target_value: + * @actionable: a #GtkActionable widget + * + * Gets the current target value of @actionabe. + * + * See gtk_actionable_set_target_value() for more information. + * + * Returns: (transfer none): the current target value + * + * Since: 3.4 + **/ GVariant * gtk_actionable_get_action_target_value (GtkActionable *actionable) { @@ -70,6 +150,33 @@ gtk_actionable_get_action_target_value (GtkActionable *actionable) ->get_action_target_value (actionable); } +/** + * gtk_actionable_set_action_target_value: + * @actionable: a #GtkActionable widget + * @target_value: a #GVariant to set as the target value, or %NULL + * + * Sets the target value of an actionable widget. + * + * If @target_value is %NULL then the target value is unset. + * + * The target value has two purposes. First, it is used as the + * parameter to activation of the action associated with the + * #GtkActionable widget. Second, it is used to determine if the widget + * should be rendered as "active" -- the widget is active if the state + * is equal to the given target. + * + * Consider the example of associating a set of buttons with a #GAction + * with string state in a typical "radio button" situation. Each button + * will be associated with the same action, but with a different target + * value for that action. Clicking on a particular button will activate + * the action with the target of that button, which will typically cause + * the action's state to change to that value. Since the action's state + * is now equal to the target value of the button, the button will now + * be rendered as active (and the other buttons, with different targets, + * rendered inactive). + * + * Since: 3.4 + **/ void gtk_actionable_set_action_target_value (GtkActionable *actionable, GVariant *target_value) @@ -80,6 +187,24 @@ gtk_actionable_set_action_target_value (GtkActionable *actionable, ->set_action_target_value (actionable, target_value); } +/** + * gtk_actionable_set_action_target: + * @actionable: a #GtkActionable widget + * @format_string: a GVariant format string + * @...: arguments appropriate for @format_string + * + * Sets the target of an actionable widget. + * + * This is a convenience function that calls g_variant_new() for + * @format_string and uses the result to call + * gtk_actionable_set_action_target_value(). + * + * If you are setting a string-valued target and want to set the action + * name at the same time, you can use + * gtk_actionable_set_detailed_action_name (). + * + * Since: 3.4 + **/ void gtk_actionable_set_action_target (GtkActionable *actionable, const gchar *format_string, @@ -92,6 +217,25 @@ gtk_actionable_set_action_target (GtkActionable *actionable, va_end (ap); } +/** + * gtk_actionable_set_detailed_action_name: + * @actionable: a #GtkActionable widget + * @detailed_action_name: the detailed action name + * + * Sets the action-name and associated string target value of an + * actionable widget. + * + * This allows for the effect of both gtk_actionable_set_action_name() + * and gtk_actionable_set_target() in the common case that the target is + * string-valued. + * + * @detailed_action_name is a string of the form + * "action::target" where action + * is the action name and target is the string to use + * as the target. + * + * Since: 3.4 + **/ void gtk_actionable_set_detailed_action_name (GtkActionable *actionable, const gchar *detailed_action_name) -- 2.30.2